Skip to content

add azure auth scope docs - #1017

Open
jgreeer wants to merge 2 commits into
agentgateway:mainfrom
jgreeer:add-azure-auth-scopes-docs
Open

add azure auth scope docs#1017
jgreeer wants to merge 2 commits into
agentgateway:mainfrom
jgreeer:add-azure-auth-scopes-docs

Conversation

@jgreeer

@jgreeer jgreeer commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

jgreeer and others added 2 commits September 3, 2026 20:28
@kristin-kronstain-brown

Copy link
Copy Markdown
Collaborator

Thanks for this PR! The prose is good, and calling out that scopes is a sibling of
explicitConfig rather than a child is exactly the detail people will get wrong.

Two things need to change before this can merge, both caused by the same thing: these
two files are shared reuse snippets, not per-version pages, so everything added here
also renders on the 1.5 and 1.4 docs, where scopes does not exist yet. These changes need to be version-gated so they display in main only.

Comment 1 (blocking) — backend-authn-azure.md:3

This file is reused by three version trees:

  • content/docs/kubernetes/main/documentation/security/backend-authn/providers/azure.md
  • content/docs/kubernetes/latest/... (1.5.x)
  • content/docs/kubernetes/1.4.x/...

So this paragraph, the new table row, and the new section all need to be wrapped in a
version gate, otherwise the 1.5 and 1.4 pages document a field their binaries reject.

For this file the gate is exclude-if="1.5.x,1.4.x". Inline for the sentence:

...an Azure AI Foundry endpoint, and it caches the credential after the first successful use.{{< version exclude-if="1.5.x,1.4.x" >}} To authenticate to Microsoft Graph or another Microsoft Entra-protected backend, configure the token scopes.{{< /version >}}

Block form for the new ## Configure token scopes section — wrap the heading and
everything under it:

{{< version exclude-if="1.5.x,1.4.x" >}}
## Configure token scopes

...
{{< /version >}}

assets/agw-docs/pages/agentgateway/llm/observability.md:45 is a working example of a
gated section that starts with a heading.

The standalone file, backend-authn-azure-standalone.md, is reused by main and
latest only, so its gate is exclude-if="1.5.x", no 1.4.x.


Comment 2 (blocking) — backend-authn-azure.md:67 (and standalone:87)

Table rows need the single-line gate form, with the shortcode opening and closing on the
same line as the row, or the table breaks:

{{< version exclude-if="1.5.x,1.4.x" >}}| `azure.scopes` | Scopes to request for the access token. When omitted, the gateway infers the scope from the backend hostname. Set 1–64 scopes. With `managedIdentity`, set exactly one scope. |{{< /version >}}

Precedent: assets/agw-docs/pages/security/backend-authn-config-k8s.md:60.


Comment 3 (nit) — backend-authn-azure-standalone.md:87

azure.scopes is placed as the first row, above azure.implicit. The rows below it are
all credential sources, and scopes is not one, so it reads oddly at the top. Moving it
to the end of the table keeps the credential sources together.


Comment 4 (optional) — backend-authn-azure-standalone.md:115

"Azure managed identity credentials support exactly one scope" is true in both modes, but
only Kubernetes enforces it. The CEL rule
(!has(self.managedIdentity) || !has(self.scopes) || self.scopes.size() == 1) is on the
CRD, so the API server rejects it there, whereas the standalone binary accepts the config
and the problem surfaces later when Azure refuses the token. Worth saying which one the
reader gets, since this is the standalone page.

@kristin-kronstain-brown kristin-kronstain-brown left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a comment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants